home *** CD-ROM | disk | FTP | other *** search
/ United Public Domain Gold 2 / United Public Domain Gold 2.iso / music_utilities / pt040.dms / pt040.adf / Programmers / PlayerLibraries / library.doc < prev    next >
Text File  |  1993-02-27  |  11KB  |  358 lines
  1. ***************************************************************************
  2. ***************************************************************************
  3.  
  4. Instructions for using "medplayer.library" and "octaplayer.library"
  5. V2.00, by Teijo Kinnunen.
  6.  
  7. ***************************************************************************
  8. ***************************************************************************
  9.  
  10.  
  11.         medplayer.library
  12.         ~~~~~~~~~~~~~~~~~
  13.  
  14. "medplayer.library" is a shared library, which can be used to load and play
  15. MED/OctaMED  4-channel modules You can call its functions from any language
  16. which supports library calls (C, Assembler, Basic...)
  17.  
  18. First  you  must  install  "medplayer.library" to your LIBS:  drawer (click
  19. Install_Libraries  to  do that).  You can also load it with ARP's "loadlib"
  20. command.
  21.  
  22. "medplayer.library"  supports only 4-channel MED songs!!  For OctaMED 5 - 8
  23. channel songs there's "octaplayer.library".
  24.  
  25. There's  a  header  file  'libproto.h'  that  contains  the  prototypes and
  26. #pragmas for use with SAS/Lattice C V5.
  27.  
  28. Here's  the  complete  list of the functions in "medplayer.library" (in RKM
  29. autodoc-style):
  30.  
  31. ---------------------------------------------------------------------------
  32. ---------------------------------------------------------------------------
  33.  
  34. GetPlayer
  35.  
  36. NAME
  37.     GetPlayer -- get and initialize the player routine
  38.  
  39. SYNOPSIS
  40.     error = GetPlayer(midi)
  41.     D0                D0
  42.  
  43. FUNCTION
  44.     This routine allocates the audio channels and CIAB timer A/B
  45.     and prepares the interrupt. If "midi" is nonzero, serial
  46.     port is allocated and initialized. You should call this
  47.     routine when your programs starts up.
  48.  
  49. INPUTS
  50.     midi =  0 no midi, 1 set up midi. When you use a song that
  51.         has only Amiga samples, there's no reason to allocate
  52.         the serial port. Then set midi to 0.
  53.  
  54. RESULT
  55.     If everything is OK, GetPlayer() returns zero. If initialization
  56.     failed or somebody else is currently using the library, then
  57.     GetPlayer() returns nonzero value.
  58.     NOTE: Even if GetPlayer() returned an error, you can still call
  59.           the library functions without making harm. They just won't
  60.           work (except LoadModule(), UnLoadModule(), RelocModule()
  61.           and GetCurrentModule(), which always work).
  62.  
  63. SEE ALSO
  64.     FreePlayer
  65.  
  66. ---------------------------------------------------------------------------
  67. ---------------------------------------------------------------------------
  68.  
  69. FreePlayer
  70.  
  71. NAME
  72.     FreePlayer -- free the resources allocated by GetPlayer()
  73.  
  74. SYNOPSIS
  75.     FreePlayer()
  76.  
  77. FUNCTION
  78.     This routine frees all resources allocated by GetPlayer().
  79.     Remember always call this routine before your program
  80.     exits. It doesn't harm to call this if GetPlayer() failed.
  81.     If you don't call this function during exit, audio channels,
  82.     timer etc. will remain allocated until reboot.
  83.  
  84. SEE ALSO
  85.     GetPlayer
  86.  
  87. ---------------------------------------------------------------------------
  88. ---------------------------------------------------------------------------
  89.  
  90. PlayModule
  91.  
  92. NAME
  93.     PlayModule -- play module from the beginning
  94.  
  95. SYNOPSIS
  96.     PlayModule(module)
  97.                A0
  98.  
  99. FUNCTION
  100.     This routine starts to play the module from the beginning.
  101.     The module can be obtained by calling LoadModule() or it can
  102.     be incorporated directly into your program. The module has to
  103.     be relocated before calling PlayModule()!
  104.  
  105. INPUTS
  106.     module = pointer to the module.
  107.  
  108. SEE ALSO
  109.     ContModule, StopPlayer
  110.  
  111. ---------------------------------------------------------------------------
  112. ---------------------------------------------------------------------------
  113.  
  114. ContModule
  115.  
  116. NAME
  117.     ContModule -- continue playing the module from where it stopped
  118.  
  119. SYNOPSIS
  120.     ContModule(module)
  121.                A0
  122.  
  123. FUNCTION
  124.     ContModule() functions just like PlayModule() except if you
  125.     have stopped playing with StopPlayer(), the playing will
  126.     continue where it stopped. When you play the module first
  127.     time, you should use PlayModule().
  128.  
  129. INPUTS
  130.     module = pointer to module.
  131.  
  132. SEE ALSO
  133.     PlayModule, StopPlayer
  134.  
  135. ---------------------------------------------------------------------------
  136. ---------------------------------------------------------------------------
  137.  
  138. StopPlayer
  139.  
  140. NAME
  141.     StopPlayer -- stops playing immediately
  142.  
  143. SYNOPSIS
  144.     StopPlayer()
  145.  
  146. FUNCTION
  147.     Stop.
  148.  
  149. SEE ALSO
  150.     PlayModule, ContModule
  151.  
  152. ---------------------------------------------------------------------------
  153. ---------------------------------------------------------------------------
  154.  
  155. DimOffPlayer
  156.  
  157. NOTE
  158.     This is an obsolete function! It was removed in V2 of the library,
  159.     and it now just does StopPlayer()!
  160.  
  161. ---------------------------------------------------------------------------
  162. ---------------------------------------------------------------------------
  163.  
  164. SetTempo
  165.  
  166. NAME
  167.     SetTempo -- modify the playing speed
  168.  
  169. SYNOPSIS
  170.     SetTempo(tempo)
  171.              D0
  172.  
  173. FUNCTION
  174.     If you want to modify the playback speed, you can call this one.
  175.     This number should be 1 - 240. Note that tempos 1 - 10 are
  176.     recognized as SoundTracker tempos.
  177.  
  178. INPUTS
  179.     tempo = new tempo
  180.  
  181. ---------------------------------------------------------------------------
  182. ---------------------------------------------------------------------------
  183.  
  184. LoadModule
  185.  
  186. NAME
  187.     LoadModule -- load a MED module from disk and relocate it
  188.  
  189. SYNOPSIS
  190.     module = LoadModule(name)
  191.     D0                  A0
  192.  
  193. FUNCTION
  194.     When you want to load a module from disk, call this function.
  195.     The function loads only MED modules (MMD0). It doesn't load
  196.     Tracker-modules, MED songs or object files. Only MMD0's
  197.     (MMD0 is the identification word at the beginning of the file).
  198.     Because the module contains many pointers, they must be
  199.     relocated. This function relocates the module automatically.
  200.     If you include the module as a binary file converted with
  201.     Objconv, YOU must relocate it. This is an easy thing to do.
  202.     Just call RelocModule().
  203.  
  204. INPUTS
  205.     name = pointer to file name (null-terminated)
  206.  
  207. RESULT
  208.     module = pointer to module. If failed to load for some reason
  209.              (disk error, out of memory, not a module), zero will
  210.           be returned.
  211.  
  212. SEE ALSO
  213.     UnLoadModule
  214.  
  215. ---------------------------------------------------------------------------
  216. ---------------------------------------------------------------------------
  217.  
  218. UnLoadModule
  219.  
  220. NAME
  221.     UnLoadModule -- frees the module from memory
  222.  
  223. SYNOPSIS
  224.     UnLoadModule(module)
  225.                  A0
  226. FUNCTION
  227.     When you don't need the module anymore, you MUST free the
  228.     memory it has used. Use this routine for it. Remember to
  229.     stop the player before unloading the module it is playing.
  230.  
  231.     NOTE: unload only those modules which are loaded with
  232.     LoadModule(). If you attempt to free module which is a part
  233.     of the program, you will cause guru 81000009/81000005.
  234.  
  235. INPUTS
  236.     module = pointer to module. If zero, nothing happens.
  237.  
  238. SEE ALSO
  239.     LoadModule
  240.  
  241. ---------------------------------------------------------------------------
  242. ---------------------------------------------------------------------------
  243.  
  244. GetCurrentModule
  245.  
  246. NAME
  247.     GetCurrentModule -- returns the address of module currently playing
  248.  
  249. SYNOPSIS
  250.     module = GetCurrentModule()
  251.     D0
  252.  
  253. FUNCTION
  254.     Simply returns the pointer of the module, which is currently
  255.     playing (or if player is stopped, which was played last). This
  256.     works also if some other task is currently playing. In this case,
  257.     because of multitasking, you should have no use for the value
  258.     (the module can be already unloaded). You may ask what use this
  259.     function has. Well, I'm not sure, but because this function
  260.     takes only 2 machine language instructions (8 bytes of memory)
  261.     there's not much harm of it.
  262.  
  263. RESULT
  264.     module = pointer to current module
  265.  
  266. ---------------------------------------------------------------------------
  267. ---------------------------------------------------------------------------
  268.  
  269. ResetMIDI
  270.  
  271. NAME
  272.     ResetMIDI -- reset all pitchbenders and modulation wheels and
  273.                  ask player to resend the preset values
  274.  
  275. SYNOPSIS
  276.     ResetMIDI()
  277.  
  278. FUNCTION
  279.     This function resets pitchbenders and modulation wheels on all
  280.     MIDI channels. It also asks the player to send again the
  281.     preset change requests for all instruments, so that the presets
  282.     will be correct if the user has changed them. It performs the
  283.     same function as MED's Ctrl-Space.
  284.  
  285. ---------------------------------------------------------------------------
  286. ---------------------------------------------------------------------------
  287. NOTE: THE FOLLOWING FUNCTIONS ARE ONLY AVAILABLE IN MEDPLAYER.LIBRARY V2
  288. OR LATER, BE SURE THAT YOU'RE REALLY USING V2 OF THE LIBRARY
  289. e.g.  MEDPlayerBase = OpenLibrary("medplayer.library",2);
  290. ---------------------------------------------------------------------------
  291. ---------------------------------------------------------------------------
  292.  
  293. SetModnum
  294.  
  295. NAME
  296.     SetModnum -- select the number of the song (in multi-module)
  297.  
  298. SYNOPSIS
  299.     SetModnum(modnum)
  300.           D0
  301.  
  302. FUNCTION
  303.     Use this function to set the number of song you want to play.
  304.     Call this before PlayModule(). 0 is the first song, 1 is the
  305.     second, and so on. If the module is not a multi-module, this
  306.     function has no affection.
  307.  
  308. ---------------------------------------------------------------------------
  309. ---------------------------------------------------------------------------
  310.  
  311. RelocModule
  312.  
  313. NAME
  314.     RelocModule -- relocate module
  315.  
  316. SYNOPSIS
  317.     RelocModule(module)
  318.             A0
  319.  
  320. FUNCTION
  321.     This function relocates the module. It should be used if you've
  322.     incorporated the module with Objconv program before using the
  323.     module. Note that LoadModule() automatically relocs everything.
  324.  
  325. ---------------------------------------------------------------------------
  326. ***************************************************************************
  327. ***************************************************************************
  328.  
  329.         octaplayer.library
  330.         ~~~~~~~~~~~~~~~~~~
  331.  
  332. This  library  is  made  for  playing OctaMED 5 - 8 channel songs ONLY.  It
  333. doesn't  support  MIDI  or 4-channel songs.  The functions in it work quite
  334. similarly as medplayer.library's functions.  See the medplayer.library docs
  335. above   for   explanation   of   the   functions,   as   the  functions  in
  336. octaplayer.library work in the same way.
  337.  
  338. The functions are:
  339.  
  340.     GetPlayer8()
  341.     FreePlayer8()
  342.     PlayModule8(module)
  343.     ContModule8(module)
  344.     StopPlayer8()
  345.     LoadModule8(filename)
  346.     UnLoadModule8(module)
  347.     SetModnum8(modnum)
  348.     RelocModule8(module)
  349.  
  350. As you can see, every function has '8' in its name, and some functions that
  351. are in medplayer.library don't exist.
  352.  
  353.  
  354. A reminder that libraries are copyrighted,they may be used within public domain
  355. and freely distributable programs,however,if you intend using them within
  356. any commercial venture,you must contact RBF Software before doing so.
  357.  
  358.